chore(web): add useLatestLoad and lint raw async effects - #1190

Adds one supported way for a screen to load data, and a lint that stops new raw async effects.

Closes #1185

The hook

useLatestLoad(inputs, load) in web/src/components/, next to usePagedList. It returns { data, error, loading, retry }.

• Each run gets its own AbortController, which is also its generation. Changing inputs, calling retry, or unmounting aborts it. An aborted run sets no state, in the failure path as much as the success path.
• load is read through useEffectEvent, so an inline arrow does not reload on every render. Only inputs and retry reload.
• data stays while a newer run loads, so loading tells a screen it may belong to the inputs being left. A failure clears it, as usePagedList does: empty is honest, stale is not.

The lint

no-restricted-syntax in web/lint/eslint.config.js, for src/routes/** and src/components/** (test files excluded). It flags an await or a .then( call anywhere inside a useEffect(...) / React.useEffect(...) call:

Load data with useLatestLoad or usePagedList (web/src/components/). A raw async effect lets a superseded response overwrite newer state (#467, #703, #918).

There are 30 existing sites in 18 files. I read each flagged line, and none is a false positive. They are recorded in web/lint/eslint-suppressions.json and none is migrated here. The hook carries the one reasoned eslint-disable, because it is the guard the rule points to.

Ceiling: the rule cannot see an async helper defined outside the effect and called from it, nor a write followed by a refresh in an event handler. Only the hooks cover those. web/AGENTS.md says so.

The suppressions growth check needed one change

The growth check from #1155 did not allow this baseline. It refused any file/rule entry that was new against the base, so this PR's 30 new entries failed it. check-suppressions.mjs now has one exception. When a rule did not apply to a file under the base's own ESLint config (calculateConfigForFile on the base eslint.config.js, presets included), that file's entry may record at most the sites the rule finds in the file's base source. So a newly enabled rule, or a widened glob, can record sites that already existed. A moved or new file, and any new site, still have to be fixed. Rules already on at the base, such as rules-of-hooks or no-debugger, are ratcheted as before.

The script takes --base <git-ref>, so CI and a local run use the same command: node lint/check-suppressions.mjs --base origin/main. A bare --base or a ref the checkout cannot resolve exits 2. A commit that predates the suppressions file runs the path check only, and the script says so.

Checks run locally

• npm run lint passes. node lint/check-suppressions.mjs --base origin/main passes, and so does the run without a base. npm run typecheck passes.
• npx vitest run src/components/useLatestLoad.test.ts src/components/usePagedList.test.tsx --maxWorkers=2: 56 passed at f74a46c4.
• Hook mutations, each reverted before the next:

Proof

The lint proof was run at 12eb9ae7; the growth table below was re-run at f74a46c4. Every scratch edit was reverted (git status clean afterwards). Absolute paths in the output are shortened to repo-relative.

The lint catches #918's pattern

#918's squash diff. ESLint, with this PR's rule and no suppressions, linted Dashboard.tsx at f4fa0570^ and at f4fa0570. Before #918 the rule fires at line 71. After it, the rule fires at lines 138, 189 and 211, which are #918's three effects. So the per-file count goes from 1 to 3, and the ratchet would have failed #918.

On today's code. A second copy of #918's yesterday-close effect, taken verbatim from f4fa0570, was added to Dashboard.tsx. That file has 7 suppressed sites.

A1. Effect added:

  useEffect(() => {
    let cancelled = false;
    getProductionReport(daysBefore(today, 1), daysBefore(today, 1))
      .then((r) => {
        if (cancelled) return;
        const yesterday = r.days[0] ?? null;
        setYesterdayClose(yesterday && yesterday.recordedFlocks > 0 && yesterday.missingFlocks === 0 ? yesterday.totalEggs : null);
      })
      .catch(() => { if (!cancelled) setYesterdayClose(null); });
    return () => { cancelled = true; };
  }, [today]);

$ npm run lint

src/routes/Dashboard.tsx
  305:5  error  Load data with useLatestLoad or usePagedList (web/src/components/). A raw async effect lets a superseded response overwrite newer state (#467, #703, #918)  no-restricted-syntax
  313:5  error  Load data with useLatestLoad or usePagedList (web/src/components/). A raw async effect lets a superseded response overwrite newer state (#467, #703, #918)  no-restricted-syntax
  317:5  error  Load data with useLatestLoad or usePagedList (web/src/components/). A raw async effect lets a superseded response overwrite newer state (#467, #703, #918)  no-restricted-syntax
  326:5  error  Load data with useLatestLoad or usePagedList (web/src/components/). A raw async effect lets a superseded response overwrite newer state (#467, #703, #918)  no-restricted-syntax
  364:5  error  Load data with useLatestLoad or usePagedList (web/src/components/). A raw async effect lets a superseded response overwrite newer state (#467, #703, #918)  no-restricted-syntax
  401:5  error  Load data with useLatestLoad or usePagedList (web/src/components/). A raw async effect lets a superseded response overwrite newer state (#467, #703, #918)  no-restricted-syntax
  412:5  error  Load data with useLatestLoad or usePagedList (web/src/components/). A raw async effect lets a superseded response overwrite newer state (#467, #703, #918)  no-restricted-syntax
  424:5  error  Load data with useLatestLoad or usePagedList (web/src/components/). A raw async effect lets a superseded response overwrite newer state (#467, #703, #918)  no-restricted-syntax
✖ 8 problems (8 errors, 0 warnings)
exit=1

A2. Reverted:
$ npm run lint

exit=0

A3. The same read through useLatestLoad instead:

  const yesterdayReport = useLatestLoad([today], () => getProductionReport(daysBefore(today, 1), daysBefore(today, 1)));

$ npm run lint

exit=0

Once the count goes over the suppressed 7, ESLint reports every site of the rule in the file, the suppressed ones included.

The growth check on a later PR

node lint/check-suppressions.mjs --base <ref>, with only the suppressions JSON edited. origin/main is this PR's base. HEAD stands in for the next PR's base.

Rows 4 and 5 were green at 12eb9ae7. They are red now, because the base source caps a new rule's entries. That closes the ceiling the earlier version of this body described: the PR that enables a rule can no longer baseline a fresh violation of it. An entry with no matching violation still fails ESLint itself (npm run lint exits 2).

Review round 1 fixes

Findings 2 and 3. Two new tests: "drops the old run's response the moment retry is called, before the new run starts" (the save-then-retry interleaving) and "reports a load that throws before returning a promise as an error, not a crash". Against the hook as at 12eb9ae7, both fail. With the fix, 8 of 8 pass. Mutations: removing the abort in retry() fails the first test, and invoking load unguarded fails the second. My first version of the retry test passed without the abort, because the new Promise wrapper adds a microtask. f2838704 lets the old run settle fully (a setTimeout(0)) before act ends, and the abort mutation then fails it.

Finding 1. The reviewer's repro, plus two controls. Base = HEAD, where the rule is on for routes and components. "Before fix" runs the check as at f2838704.

Finding 4.